home *** CD-ROM | disk | FTP | other *** search
/ Linux Cubed Series 7: Sunsite / Linux Cubed Series 7 - Sunsite Vol 1.iso / system / network / admin / xinetd.2 / xinetd / xinetd.2.1.7-linux.4 / libs / src / sio / README < prev    next >
Encoding:
Text File  |  1993-07-25  |  4.6 KB  |  129 lines
  1. ======================================================================
  2. NOTE: I use vi with a tabstop value of 3. Using the same tabstop
  3.         value will make the text/code look properly indented.
  4. ======================================================================
  5.  
  6.  
  7. 1. What is SIO ?
  8.  
  9. SIO is a library that provides _stream_ I/O which is what most Unix
  10. programs do. As such it is a competitor to stdio.
  11.  
  12.  
  13. 2. Why would you care to use it ?
  14.  
  15. a. SIO is a little faster than stdio
  16. b. SIO provides an easier-to-use interface (IMHO)
  17. c. SIO is capable of using memory mapping for reading files if the operating
  18.     system supports it.
  19. d. If you have a program that uses read(2)/write(2) it is trivial
  20.    to convert it to use SIO (just replace read with Sread and 
  21.    write with Swrite)
  22. e. You get source
  23.  
  24.  
  25.  
  26. 3. Setting up the Stream I/O (SIO) library
  27.  
  28. There are 3 steps to the process:
  29.     1) modifying the SIO configuration file (but you can skip this
  30.         step if you are using one of the operating systems listed below).
  31.     2) testing SIO
  32.     3) installing the library and manpages
  33.  
  34.  
  35. 3.1. How to compile the Stream I/O (SIO) library
  36.  
  37. All the system-dependent stuff of SIO is placed in the sioconf.h file.
  38. If your system is not listed below, you will need to read that file
  39. to see what flags you need to set to properly compile SIO.
  40.  
  41. For the following systems, here is what you need to do:
  42.  
  43.     SunOS 4.x:
  44.         make "DEFS=-DHAS_MMAP -DHAS_ONEXIT -DHAS_MEMOPS -DHAS_ISATTY"
  45.  
  46.     SunOS 5.x (aka Solaris 2.y):
  47.         make "DEFS=-DHAS_MMAP -DHAS_ATEXIT -DHAS_MEMOPS -DHAS_ISATTY"
  48.     (I don't have access to a system running Solaris 2.y so I have not
  49.     tested this)
  50.  
  51.     Ultrix 4.x:
  52.         make "DEFS=-DHAS_MEMOPS -DHAS_ATEXIT -DHAS_ISATTY"
  53.  
  54. If your system is one of the above, then you can skip to the next subsection.
  55. However, I should mention that the library compiles by default with
  56. debugging enabled (i.e. uses the -g flag of cc). You can override this
  57. by appending to the invocation of 'make' the argument "DEBUG=-O"
  58.  
  59. If your system is not among the above, then you will need to modify the
  60. sioconf.h file. You do this by uncommenting the inclusion of
  61. customconf.h. Then, you can override all constants/macros defined in
  62. sioconf.h by defining them first in customconf.h.  Please read
  63. sioconf.h for more information on what constants/macros can be
  64. defined.
  65.  
  66. The Makefile has a header that explains what the Makefile can do.
  67. The only flag that you may want to define is -DDEBUG which enables 
  68. assertions in the SIO code (if an assertion fails, the program is 
  69. terminated with an error message that lists the SIO file and line 
  70. number where the error occured).
  71.  
  72.  
  73. 3.2. Testing SIO
  74.  
  75. After you have successfully compiled SIO, you can use the programs in
  76. the "suite" directory to test the SIO functions.  Testing should be
  77. done before installing the library.
  78. The script testlib does everything; just type:
  79.  
  80.     testlib all
  81.  
  82. The script sprint_test (invoked by testlib) tests Sprint by using a variety 
  83. of formats and comparing its output with that of an ANSI-compatible printf.
  84. At least on Ultrix 4.1 and 4.2 this test fails because printf is not 
  85. ANSI-compatible.
  86. In such a case, you can test the rest of the SIO functions by typing:
  87.  
  88.     testlib all Sprint
  89.  
  90. (anything after the 'all' argument is interpreted as a function that
  91. should not be tested).
  92.  
  93. The README file in the "suite" directory describes how to do a
  94. few more tests that cannot be done automatically.
  95.  
  96.  
  97. 3.3. Installing the library and manpages
  98.  
  99. The 'make' command will create libsio.a in the current directory.
  100. The Makefile includes an "install" target. Doing a 'make install' will 
  101. cause the following:
  102.  
  103. a) libsio.a will be installed in LIBDIR
  104. b) the necessary SIO header files will be installed in INCLUDEDIR
  105. c) the SIO man pages will be installed in MANDIR
  106.  
  107. LIBDIR, INCLUDEDIR, and MANDIR are Makefile variables that you can edit in
  108. the Makefile or override when you invoke 'make'.
  109. Here is a sample command to install SIO:
  110.  
  111.     make install LIBDIR=/usr/local/lib INCLUDEDIR=/usr/local/include MANDIR=/usr/local/man/man3
  112.  
  113.  
  114. 4. Epilogue
  115.  
  116. Feel free to modify SIO to suit your needs. Please let me know of
  117. any bugs you find.
  118.  
  119. If you want to distribute your modifications, please read the COPYRIGHT
  120. file.  It basically says that you are free to redistribute as long as
  121. you retain the original copyright notice and you make sure that your
  122. modifications are identifiable. In order to achieve this I have
  123. reserved the first 3 components of the version number (for example,
  124. 1.4.2) and you can identify your mods by appending another component to
  125. that version number (for example, 1.4.2.A2). Also, if you distribute a
  126. modified version of the library, you take full responsibility for any
  127. bugs in the code (not just your code; the whole thing).
  128.  
  129.